home *** CD-ROM | disk | FTP | other *** search
/ Pluspack 1 / Caligari Corporation Pluspack1 1998.iso / TSX_SDK / tsxINC / tsxGNode.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-01-28  |  8.9 KB  |  264 lines
  1. //******************************************************************************
  2. //    File: tsxGNode.h
  3. //  Module: trueSpace eXtensions API
  4. //   Descr: Definition of tsxGNODE
  5. //******************************************************************************
  6.  
  7. #ifndef TSXGNODE_H
  8. #define TSXGNODE_H
  9.  
  10.  
  11. #include "tsxTypes.h"
  12.  
  13.  
  14. enum tsxUNITS {
  15.     e_tsxUNITS_MILLIMETERS = 0,
  16.     e_tsxUNITS_CENTIMETERS,
  17.     e_tsxUNITS_METERS,
  18.     e_tsxUNITS_KILOMETERS,
  19.     e_tsxUNITS_INCHES,
  20.     e_tsxUNITS_FEET,
  21.     e_tsxUNITS_YARDS,
  22.     e_tsxUNITS_MILES,
  23.     e_tsxUNITS_POINTS,
  24. };
  25.  
  26. //------------------------------------------------------------------------------
  27. //------------------------------------------------------------------------------
  28.  
  29. // A tsxGNODE is the abstract type for Nodes in a Scene Graph.
  30. // All tsxGNODEs have position and orientation, as defined by their Axes,
  31. // and can be visible while editing. 
  32. // A tsxGNODE adds the following attributes to tsxSOBJ:
  33. //      - Name
  34. //      - parent
  35. //      - children
  36. //      - siblings
  37. //      - Axes position and orientation
  38.  
  39. // NOTE on Transformations ...
  40. //   Transformations are applied to a GNode by specifying the amount of change
  41. //   from the current configuration.  For example, `tsxGNodeTranslate' takes a
  42. //   translation vector as argument to specify the direction and distance of
  43. //   translation.  This relative transformation can be given in either the World
  44. //   frame (e.g. the translation vector is relative to the World axes) or in
  45. //   the Model frame.  The Model frame for a GNode is specified by the position
  46. //   and orientation of its Axes. The function `tsxGNodeGetPosition' can be used
  47. //   to get the position of the GNode's Model-frame origin, and the function
  48. //   `tsxGNodeGetAxes' can be used to get their orientation.  These two pieces
  49. //   of information can be accessed together as a combined pure rotation matrix
  50. //   through the function `tsxGNodeGetPureTransform'.
  51. //
  52. //   Only MNODE object types allow their Model-frame to be modified (tsxMNode.h).
  53.  
  54.  
  55. //------------------------------------------------------------------------------
  56. //    GNode type check
  57. //------------------------------------------------------------------------------
  58.  
  59. // e_tsxTRUE if pSobj is a GNode
  60. TSXAPIFN tsxBOOL tsxIsGNode( tsxSOBJ* pSobj );
  61.  
  62.  
  63. //------------------------------------------------------------------------------
  64. //    Management
  65. //------------------------------------------------------------------------------
  66.  
  67. // Get a copy of the entire tree rooted at a GNode
  68. TSXAPIFN tsxERR tsxGNodeCopy(
  69.     tsxGNODE* pGNode,        // The GNode to copy
  70.     tsxGNODE** ppGNodeCopy    // Ptr to Copy placed here, on success
  71.     );
  72.  
  73.  
  74. //------------------------------------------------------------------------------
  75. //    Traverse Scene Graph
  76. //------------------------------------------------------------------------------
  77.  
  78. // Returns: 0         if pGNode is the Scene object;
  79. //          pGNode  if parent of pGNode is the Scene object,
  80. //                  or pGNode has no parent;
  81. //     else ptr to highest tsxGNODE ancestor of pGNode below Scene.
  82. TSXAPIFN tsxGNODE* tsxGNodeGetRoot( tsxGNODE* pGNode );
  83.  
  84. // Get the parent node in the scene graph.
  85. TSXAPIFN tsxGNODE* tsxGNodeGetParent( tsxGNODE* pGNode );
  86.  
  87. // Returns e_tsxTRUE if pGNode is a member of the Scene at some level.
  88. TSXAPIFN tsxBOOL tsxIsGNodeInScene( tsxGNODE* pGNode );
  89.  
  90. // Get the first child of a Group or LOD object.
  91. TSXAPIFN tsxGNODE* tsxGNodeGetFirstChild( tsxGNODE* pGNode );
  92.  
  93. // Get the next node of valid tsx Type
  94. TSXAPIFN tsxGNODE* tsxGNodeGetNext( tsxGNODE* pGNode );
  95.  
  96. // Get the prev node of valid tsx Type
  97. TSXAPIFN tsxGNODE* tsxGNodeGetPrev( tsxGNODE* pGNode );
  98.  
  99. // Returns e_tsxTRUE if pCheckGNode is a node in the tree rooted at pGNode.
  100. TSXAPIFN tsxBOOL tsxIsGNodeSubobj( tsxGNODE* pGNode, tsxGNODE* pCheckGNode );
  101.  
  102.  
  103. //------------------------------------------------------------------------------
  104. //    Drawing/Rendering
  105. //------------------------------------------------------------------------------
  106.  
  107. // Draws pGNode in the current view, in the current view's rendering mode.
  108. TSXAPIFN void tsxGNodeDraw( tsxGNODE* pGNode );
  109.  
  110.  
  111. //------------------------------------------------------------------------------
  112. //    Name
  113. //------------------------------------------------------------------------------
  114.  
  115. // Gets the Name of a GNode.
  116. // Returns length of name. (0 if not valid request or null name)
  117. TSXAPIFN int tsxGNodeGetName(
  118.     tsxGNODE* pGNode,
  119.     char*     pName,    //buffer where name is copied
  120.     int       iNameSz    //Size of pName buffer
  121.     );
  122.  
  123. // Sets the Name of a GNode.
  124. // Returns 0 on success.
  125. TSXAPIFN tsxERR tsxGNodeSetName( tsxGNODE* pGNode, char* szNewName );
  126.  
  127.  
  128. //------------------------------------------------------------------------------
  129. //    Model-frame Axes
  130. //------------------------------------------------------------------------------
  131.  
  132. // Get the GNode's position in World coordinates.
  133. // Returns 0 if not GNODE, else posn.
  134. TSXAPIFN CtsxVector3f* tsxGNodeGetAxesPosition(
  135.     tsxGNODE* pGNode,
  136.     CtsxVector3f* posn
  137.     );
  138.  
  139. // Get the GNode's model axes orientation, as a triple of normalized orthogonal
  140. // vectors pointing in the directions of GNode's X, Y and Z.
  141. // Returns 0 if not GNODE, else axes.
  142. TSXAPIFN CtsxAxes3f* tsxGNodeGetAxesOrientation(
  143.     tsxGNODE* pGNode,
  144.     CtsxAxes3f* axes
  145.     );
  146.  
  147. // Setting the axes orientation and position is only allowed for MNODEs.
  148.  
  149. // Add the bounding box of GNode to input BBox.
  150. // Not valid for Track and Path objects.
  151. // The resulting BBox will also enclose the input BBox bounds. To get BBox
  152. // of only pGNode, use `tsxBBoxInit()' before calling this function.
  153. TSXAPIFN tsxERR tsxGNodeGetBBox(
  154.     tsxGNODE* pGNode,    //Non Track/Path GNode
  155.     CtsxBBox3f* pBBox    //BBox updated with result.
  156.     );
  157.  
  158. //------------------------------------------------------------------------------
  159. //    Location, Rotation, Size
  160. //------------------------------------------------------------------------------
  161.  
  162. // Get units of GNode. Returns e_tsxMETERS if GNode is not valid.
  163. TSXAPIFN tsxUNITS tsxGNodeGetUnits(tsxGNODE* pGNode);
  164.  
  165. // Set units of GNode.
  166. TSXAPIFN void tsxGNodeSetUnits(tsxGNODE* pGNode, tsxUNITS units);
  167.  
  168. // Get the location of GNode.
  169. // Returns 0 if not GNODE, else loc.
  170. TSXAPIFN CtsxVector3f* tsxGNodeGetLocation(
  171.     tsxGNODE* pGNode,
  172.     CtsxVector3f* loc
  173.     );
  174.  
  175. // Get the euler angles of GNode's orientation.
  176. // Returns 0 if not GNODE, else rot.
  177. TSXAPIFN CtsxVector3f* tsxGNodeGetRotation(
  178.     tsxGNODE* pGNode,
  179.     CtsxVector3f* rot
  180.     );
  181.  
  182. // Get the size of GNode.
  183. // Returns 0 if not GNODE, else size.
  184. TSXAPIFN CtsxVector3f* tsxGNodeGetSize(
  185.     tsxGNODE* pGNode,
  186.     CtsxVector3f* size
  187.     );
  188.  
  189. // Set the location of GNode.
  190. TSXAPIFN void tsxGNodeSetLocation(
  191.     tsxGNODE* pGNode,
  192.     CtsxVector3f* loc
  193.     );
  194.  
  195. // Set the euler angles of GNode's orientation.
  196. TSXAPIFN void tsxGNodeSetRotation(
  197.     tsxGNODE* pGNode,
  198.     CtsxVector3f* rot
  199.     );
  200.  
  201. // Set the size of GNode.
  202. TSXAPIFN void tsxGNodeSetSize(
  203.     tsxGNODE* pGNode,
  204.     CtsxVector3f* size
  205.     );
  206.  
  207.  
  208. //------------------------------------------------------------------------------
  209. //    Transformation
  210. //------------------------------------------------------------------------------
  211.  
  212. // Returns Transformation matrix representation of the GNode's axes,
  213. //         with only Rotation and Translation elements,
  214. //         and no Scaling/Shearing factors.
  215. //         0 if not GNode
  216. TSXAPIFN CtsxTxmx3f* tsxGNodeGetPureTransform(
  217.     tsxGNODE* pGNode,
  218.     CtsxTxmx3f* pTxmx
  219.     );
  220.  
  221. // Returns Transformation matrix of GNode,
  222. //         0 if not GNode
  223. TSXAPIFN CtsxTxmx3f* tsxGNodeGetTransform(
  224.     tsxGNODE* pGNode,
  225.     CtsxTxmx3f* pTxmx
  226.     );
  227.  
  228. // Translate GNode by pVec, in the specified reference frame.
  229. TSXAPIFN void tsxGNodeTranslate(
  230.     tsxGNODE* pGNode, 
  231.     CtsxVector3f* pVec, // translation vector
  232.     tsxFRAMEID frameid   // Reference frame for pVec
  233.     );
  234.  
  235. // Rotate by fAngle radians about pAxis passing thru pCenter,
  236. // in the specified reference frame.
  237. TSXAPIFN void tsxGNodeRotate(
  238.     tsxGNODE* pGNode, 
  239.     CtsxVector3f* pCenter,    //Center of rotation.
  240.     CtsxVector3f* pAxis,    //Rotation axis passing thru pCenter.
  241.     float fAngle,        //Radians. Rotation angle.
  242.     tsxFRAMEID frameid
  243.     );
  244.  
  245. // Scale by factors along each axis, in the specified reference frame.
  246. // Scale factors must be non-zero.
  247. TSXAPIFN void tsxGNodeScale(
  248.     tsxGNODE* pGNode, 
  249.     CtsxVector3f* pScaleFacs,    //x, y, z scale factors (non-zero)
  250.     tsxFRAMEID frameid
  251.     );
  252.  
  253. // Scale by factor UNIFORMLY along each axis, in the specified reference frame.
  254. // Scale factor must be non-zero.
  255. TSXAPIFN void tsxGNodeScaleUniform(
  256.     tsxGNODE* pGNode, 
  257.     float fScaleFac,
  258.     tsxFRAMEID frameid
  259.     );
  260.  
  261.  
  262. //******************************************************************************
  263. #endif //TSXGNODE_H
  264.